NewPictInfo

NewPictInfo
Header:	PictUtils.h		Carbon status:	Supported

Begins collecting pictures, pixel maps, and bitmaps for a survey of pictures.

OSErr NewPictInfo (
    PictInfoID *thePictInfoID, 
    SInt16 verb, 
    SInt16 colorsRequested, 
    SInt16 colorPickMethod, 
    SInt16 version
);

thePictInfoID

On return, a unique value that denotes your collection of pictures, pixel maps, or bitmaps. Use this ID number when surveying multiple pictures, pixel maps, and bitmaps for information.

verb

A value indicating what type of information you want the RetrievePictInfo function to return in a PictInfo structure. See “Verb Constants” for a description of the values you can use here.

The constants recordComments and recordFontInfo and the values they represent have no effect when gathering information about the pixel maps and bitmaps included in your survey.

Because the Palette Manager adds black and white when creating a palette, you can specify the number of colors you want minus 2 in the colorsRequested parameter and specify the constant suppressBlackAndWhite in the verb parameter when gathering colors destined for a Palette structure or a screen.

colorsRequested

From 1 to 256, the number of colors you want included in the ColorTable or Palette structure returned by the RetrievePictInfo function via a PictInfo structure.

colorPickMethod

The method by which colors are selected for the ColorTable or Palette structure included in the PictInfo structure returned by the RetrievePictInfo function. See “Color Selection Method Constants” for a description of the values you can use here.

You can also create your own color-picking method in a resource file of type 'cpmt' and pass its resource ID in the colorPickMethod parameter. The resource ID must be greater than 127.

version

Always set this parameter to 0.

function result: A result code.

DISCUSSION

To add the information for a picture to your survey, use the RecordPictInfo function. To add the information for a pixel map or a bitmap to your survey, use the RecordPixMapInfo function. For each of these functions, identify the survey with the ID number returned by NewPictInfo.

Use the RetrievePictInfo function to return information about the pictures, pixel maps, and bitmaps in the survey. The RetrievePictInfo function returns your requested information in a PictInfo structure.

Use the verb parameter for NewPictInfo to specify whether you want to gather comment or font information for the pictures in the survey. If you want to gather color information, use the verb parameter for NewPictInfo to specify whether you want this information in a ColorTable structure, a Palette structure, or both. The PictInfo structure returned by the RetrievePictInfo function will then include a handle to a ColorTable structure or a Palette structure, or handles to both. If you want color information, be sure to use the colorPickMethod parameter to specify the method by which to select colors.

The Picture Utilities provide two color-picking methods: one (specified by the popularMethod constant) that gives you the most frequently used colors and one (specified by the medianMethod constant) that gives you the widest range of colors. If you specify the systemMethod constant, the Picture Utilities choose the method; currently they always choose popularMethod. You can also supply a color-picking method of your own.

SPECIAL CONSIDERATIONS

The NewPictInfo function may move or purge memory.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.